Each function and procedure should be documented with a comment either just before or right after the IS
or AS
keyword it
to explain its goal and how it works.
Noncompliant code example
CREATE FUNCTION my_function RETURN PLS_INTEGER AS
BEGIN
RETURN 42;
END;
/
CREATE PACKAGE my_package AS
PROCEDURE my_procedure;
FUNCTION my_function RETURN PLS_INTEGER;
END my_package;
/
Compliant solution
CREATE FUNCTION my_function RETURN PLS_INTEGER AS
-- Computes the meaning of life
BEGIN
RETURN 42;
END;
/
CREATE PACKAGE my_package AS
-- This is documentation
PROCEDURE my_procedure;
/*
This is documentation
*/
FUNCTION my_function RETURN PLS_INTEGER;
END my_package;
/
Exceptions
Functions are procedures declared in package bodies, and anonymous PL/SQL blocks do not have to be documented.
DECLARE
PROCEDURE helper_procedure AS
BEGIN
NULL;
END;
BEGIN
helper_procedure;
END;
/
CREATE PACKAGE my_package AS
-- This is documentation
PROCEDURE public_procedure;
END my_package;
/
CREATE PACKAGE BODY my_package AS
PROCEDURE helper_procedure AS
BEGIN
NULL;
END;
PROCEDURE public_procedure AS
BEGIN
helper_procedure;
END;
END my_package;
/